Keep DocumentDB Local state in sync, explain failures, and unify tree progress - #876

Fixes #873

Problem

Stopping DocumentDB Local outside VS Code left the extension believing it was still running, and the resulting connection failure surfaced as a raw driver error (ECONNREFUSED, a server selection timeout) that said nothing about the container. The reporter asked for two things: validate the container on connect, and recover from, or at least explain, the failure afterwards.

The first half was straightforward. The second half turned out to be a general problem: a connection can fail for reasons that have nothing to do with the database, and we had no way for the component that owns that infrastructure to say so.

What this does

Quick Start state accuracy

• Quick Start reconciliation is demand-driven, on first expansion or direct use, instead of running at extension activation.
• The Quick Start root refresh performs an authoritative durable-store and Docker reconciliation, with tracing and retry-safe failure handling.
• Running, stopped, missing and credentials-missing states stay accurate while avoiding redundant background probes.
• Expanding the cluster preflights the container, so stale Running state can never reach the database client. A stopped instance offers to start.
• Managed-instance tooltips carry container and Docker host details, including the conventional 12-character container ID.

Error translation (ConnectionDiagnosticsService)

A registry where the source that owns the infrastructure explains a failure in its own words. Providers ship for DocumentDB Local (Docker), Kubernetes port forwarding, and Atlas TLS rejections.

It is deliberately translation only. Providers return text; they never show UI, never recover, never retry, and never touch the error object. That last constraint is load-bearing: a lot of code here inspects errors by identity rather than text, and all of it would break silently otherwise.

Covered surfaces. Cluster connect and list databases in all views; everything below a cluster in all four tree views, via one catch in BaseExtendedTreeDataProvider; the Collection view query and Query Insights; the Document view; tree-node commands; the shell; the query playground. Background paths that show nothing (count badges, prefetches) are deliberately left alone.

Webviews ask through a single shared procedure, common.explainOperationFailure, since an explanation cannot ride along on an error across the tRPC boundary.

Shell terminal no longer disappears on a failed connect

The connect-failure path wrote an error line and then immediately fired the close emitter, which disposes the terminal and takes the message with it. There is no VS Code setting for this: for an extension-owned Pseudoterminal, onDidClose always disposes.

It now shows a prompt instead. ShellSessionManager.evaluate() re-runs initialize() while the session is uninitialized, which a failed connect leaves it as, so the next command the user types becomes the retry: start the container, press Enter, you are connected. The failure is also reported through two channels that outlive the terminal, a notification and an outputChannel.error line carrying the raw driver message plus the provider id and explanation, so a shared output channel is enough to diagnose a report remotely.

Message style

Messages avoid asserting what happened, since we cannot know. "We cannot find the DocumentDB Local container. It was very likely removed outside VS Code. You can recreate it from the Connections view, which reuses the existing data volume."

Documentation

.github/skills/error-translation/SKILL.md covers the one rule (providers translate, never show UI), the three ways a provider identifies its own clusters, why verdicts must not be cached, the identity checks that forbid touching errors, which background paths to leave alone, and the message conventions.

Follow-up

#877 captures ideas for where this could go next (recovery buttons, self healing, proactive detection), explicitly as ideas needing discussion rather than a plan. It is labelled on-hold and needs-triage.

Not included here: an Azure diagnostics provider, so Azure firewall and IP-rule rejections still surface raw. Noted in #877.

Review follow-ups

A review pass over the branch turned up a set of defects. Each is fixed here in its own commit.

Two were user-visible regressions.

Making hydration lazy also made it fatal. listByLabel rejects when there is no docker binary or
the daemon is stopped, and both Quick Start entry points awaited ensureHydrated() unguarded, so
the tree row rendered empty behind an error toast and the webview, the one surface that can diagnose
Docker, never opened. Both call sites now tolerate the rejection; the service stays retryable.

registerCommandWithTreeNodeUnwrappingAndModalErrors asked for an explanation on every error that
was not a UserFacingError, and a provider is allowed to answer without inspecting the error at
all. Escaping a wizard on a stopped instance therefore raised a modal saying DocumentDB Local was
not running. explain() now returns undefined for a UserCancelledError before any provider is
asked.

The rest

• inspectContainer reports "could not ask" and "not there" identically, so stopping Docker Desktop
  made the preflight assert the container had been removed outside VS Code and recommend recreating
  it. The preflight confirms the daemon before concluding missing, and a new dockerUnreachable
  verdict carries wording that matches what actually happened.
• prepareForConnection() corrected state, fired the status emitter and could warn, so the
  error-translation provider was repairing state and repainting the tree while claiming to only
  translate. The verdict is split out as a read-only inspectManagedInstance().
• A diagnosis becomes the heading of a modal, where the four-line bulleted Atlas text rendered as a
  block of bold lines. The provider now returns a single-paragraph summary; the Discovery-view modal
  keeps the long form where it belongs, in the detail area.
• MessageOptions.detail is only rendered for modal messages, so the tree base class was
  suppressing the default notification and then hiding the driver text entirely. It is appended to
  the message instead, matching displayErrorMessage.
• The shell's connect-failure line goes to an output channel users are encouraged to share, and a
  driver error can quote the connection string, which for a Quick Start instance carries a generated
  password. Cached secrets are redacted first.
• Expanding the managed cluster raised a modal that blocked the expansion until it was answered and
  then left the node empty, and every other non-ready verdict rendered as silence. Each verdict now
  gets an actionable row, which also removes a module-level prompt singleton that would have been
  shared across aliases.
• The status events reconciliation fires re-enter getChildren() once hydration has completed,
  and the background-probe cooldown was still unarmed, so the very first expansion started a
  redundant docker inspect and flashed Refreshing… on the row. Hydration now arms the cooldown,
  as refreshHydratedState() already did.
• The explain() deadline was per provider, so three registered sources could hold an error back
  for 15s on top of the driver's own timeout. It is now one budget for the whole call.
• Smaller: unwrapArgs moved back inside the guarded block, display labels instead of raw
  identifiers (NotInstalled, unixSocket) in the tooltip, narrower markdown escaping, and
  progress during the explicit deep refresh.

Two findings were left alone on purpose. Collapsing the Quick Start root is what makes hydration
lazy, and the Quick Start provider ignoring the error shape is the premise that lets it answer at
all; both are recorded with their reasoning rather than silently dropped.

The review and its resolution live in docs/ai-and-plans/PRs/876-quickstart-error-translation-review.md.

One way to show progress in the tree

Quick Start drew its own loading~spin icons and a · Refreshing… text hint instead of the tree
framework's node progress (ext.state), so one view expressed the same idea two ways. Three of
those sites were also plain gaps: starting or stopping from the tree gave no feedback at all until
the service pushed a new state, and the node's own refresh spun the view title rather than the node.

The obstacle was that the work is service-owned. A start can come from the Quick Start webview, a
lifecycle command, or the background freshness probe, so the row had nothing to await.
QuickStartService now publishes an awaitable handle for in-flight work (getInFlightOperation)
alongside a dedicated onDidChangeOperation event, kept separate from onDidChangeStatus because
that one's listeners rebuild the whole Connections view. A small bridge maps the handle onto
ext.state.runWithTemporaryDescription for the instance row.

• The busy child row, the Starting/Stopping spinners and the · Refreshing… hint are gone. The row
  is decorated the way a deleting collection or an importing database already is.
• Transitional rows keep their state_* context values. The framework overlays description and
  icon but never contextValue, which the lifecycle menus gate on.
• The bridge is deferred through a microtask: work can start from inside a tree render, and applying
  state fires a refresh synchronously.
• The lifecycle commands are deliberately not wrapped as well. The bridge already covers every
  origin, and two owners of one indicator would clip it early.
• Provisioning keeps its own spinner. It is also reachable by observation, from a durable lease
  written by another window or a previous session, so there is no promise to await and no instance
  row to attach to yet. The call site records that reasoning.

Transitional rows and the overlay now render identical strings, with the host dropped from both: it
is not actionable mid-transition, and two copies of one sentence can only drift apart. Where a host
does belong, as in Running · localhost:10260, it is composed outside the localized string so the
separator is not something a translation can reorder, and the state half comes from the same
function that builds the tooltip.

New tests cover the operation handle in the service and the bridge itself: the correct row and
label per operation kind, no stacking while one operation runs, pickup of the next operation, and
silence when nothing is in flight.

Cluster commands on the managed instance

The running instance row looked like a cluster but carried none of the cluster commands, so New
Database, Launch Shell and Refresh were missing, and Copy Connection String had to exist twice.
That is UX review item 20, from #790.

The row deliberately still does not take treeItem_documentdbcluster. That tag gates thirteen
entries, six of which resolve the node through connection storage — rename, move, remove, update
credentials, update connection string, plus Azure data migration — and a service-owned instance has
no storage record for them to act on. Granting the tag and excluding the six would mean every
future cluster command reaches this row by default, which is the wrong default for a node that is
not a stored connection.

Commands are opted in individually instead, gated to state_running because every other state
renders a plain row with no cluster to dereference. The contribution test pins both directions:
the three that must appear, the six that must not, and a guard that the tree item never starts
using CLUSTER_ITEM_CONTEXT_VALUE.

Copy Connection String and Copy Password stay as Quick Start commands rather than folding into the
generic ones: they are also offered while the instance is stopped, where the row is not a
cluster item at all and the generic command would have no getCredentials() to call.

Second review pass

A later review found four more defects. All four were real, and three were surfaces this description claimed but the code had not reached. Each is fixed in 0194ac26.

• A Docker outage still read as a deleted container. The preflight learned to tell "could not ask" from "not there"; the background freshness probe kept the old logic and set missing on any empty inspect. Stopping Docker Desktop under an expanded node offered to recreate a container that was sitting on disk. refreshLiveState() now confirms the daemon is answering first, and keeps the last known state otherwise.
• The database commands were never wired up. Only connection-management commands used the diagnostics-aware wrapper. Reusing the modal wrapper would have promoted every UserFacingError from nine commands into a blocking dialog, so there is a new registerCommandWithTreeNodeUnwrappingAndDiagnostics instead: same translation, reported the way those commands already report failures.
• The explain deadline did not stop anything. Promise.race abandons the losing promise rather than cancelling it, so later providers were still queried and a late answer still recorded connectionDiagnostics.explained for a caller that had already been handed undefined. The deadline is now an AbortSignal checked before each provider and again after each await.
• The shell was only half covered. A session that connects fine can still break underneath the user; that path printed the raw driver error. handleEvalError now asks for a diagnosis too, keeping the SettingsHintError hint and the error-code-50 tip intact. It became async as a result, so a failed command can wait on a diagnosis before the prompt returns — bounded by the 5s deadline.

Also from the first review: the tooltip's product labels were raw strings while the webview localizes the same words, and 'Dev Container' differed from the webview's 'Dev container' by one capital letter, which extracted as a second key. Both fixed; net zero new strings.

Validation

• npm run l10n
• npm run prettier-fix
• npm run lint — clean
• npx jest --no-coverage — 218 suites, 3,499 tests
• npm run build — clean

New tests cover the service (first answer wins, throwing and stalling providers are skipped, the error comes back untouched), each of the three providers, and the tree base class translation including a regression guard that background count paths never invoke it.